---
title: 프로젝트 구조
description: Astro로 프로젝트를 구성하는 방법을 알아보세요.
i18nReady: true
---
import { FileTree } from '@astrojs/starlight/components';

`create astro` CLI 마법사로 생성된 새 Astro 프로젝트에는 이미 일부 파일과 디렉터리가 포함되어 있습니다. 그렇지 않다면, Astro의 파일 구조를 직접 생성해야합니다.

Astro 프로젝트가 구성되는 방식과 새 프로젝트에서 찾을 수 있는 일부 파일은 다음과 같습니다.

## 디렉터리 및 파일

Astro는 독창적인 디렉터리 레이아웃을 활용하여 프로젝트를 구성합니다. 모든 Astro 프로젝트의 루트 디렉터리에는 다음과 같은 디렉터리와 파일이 포함되어야 합니다.

- `src/*` - 프로젝트 소스 코드 (컴포넌트, 페이지, 스타일 등)
- `public/*` - 코드가 아니거나 처리되지 않아야 하는 자산 (글꼴, 아이콘 등)
- `package.json` - 프로젝트 매니페스트
- `astro.config.mjs` - Astro 구성 파일 (권장)
- `tsconfig.json` - TypeScript 구성 파일 (권장)

### 프로젝트 트리 예시

일반적인 Astro 프로젝트 디렉터리는 다음과 같습니다.

<FileTree>
- public/
  - robots.txt
  - favicon.svg
  - social-image.png
- src/
  - components/
    - Header.astro
    - Button.jsx
  - layouts/
    - PostLayout.astro
  - pages/
    - posts/
      - post1.md
      - post2.md
      - post3.md
    - index.astro
  - styles/
    - global.css
- astro.config.mjs
- package.json
- tsconfig.json
</FileTree>

### `src/`

`src/` 디렉터리는 대부분의 프로젝트 소스 코드가 있는 곳입니다. 여기에는 다음이 포함됩니다.

- [페이지](/ko/basics/astro-pages/)
- [레이아웃](/ko/basics/layouts/)
- [Astro 컴포넌트](/ko/basics/astro-components/)
- [UI 프레임워크 components (React 등)](/ko/guides/framework-components/)
- [스타일 (CSS, Sass)](/ko/guides/styling/)
- [Markdown](/ko/guides/markdown-content/)

Astro는 `src/` 디렉터리 내 파일들을 처리, 최적화, 번들링하여 브라우저에 제공되는 최종 웹사이트를 만듭니다. 정적 파일들이 포함되어 있는 `public/` 디렉터리와는 달리 `src/` 디렉터리 내 파일들은 Astro에 의해 자동으로 빌드되고 처리됩니다.

Astro 컴포넌트와 같은 일부 파일은 작성된 그대로 브라우저로 전송되지 않고 정적 HTML로 렌더링됩니다. CSS와 같은 다른 파일은 브라우저로 전송되지만 성능을 위해 최적화되거나 다른 CSS 파일과 함께 번들링되어 제공될 수 있습니다.

:::tip
이 가이드는 Astro 커뮤니티에서 사용되는 몇 가지 인기 있는 규칙을 설명합니다. Astro에서 예약되어 이름을 임의로 변경할 수 없는 디렉터리는 `src/pages/` 및 `src/content/` 뿐입니다. 이 두 디렉터리를 제외한 나머지 디렉터리에 대해 가장 적합한 방식으로 이름을 변경하고 재구성할 수 있습니다.
:::

### `src/components`

**컴포넌트**는 재사용 가능한 HTML 코드 단위입니다. 이는 [Astro 컴포넌트](/ko/basics/astro-components/) 또는 React나 Vue와 같은 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/)일 수 있습니다. 이 디렉터리에 모든 프로젝트 컴포넌트를 그룹화하고 구성하는 것이 일반적입니다.

이는 Astro 프로젝트의 일반적인 규칙이지만 필수는 아닙니다. 원하는 대로 컴포넌트를 구성해 보세요!

### `src/content`

`src/content/` 디렉터리는 [콘텐츠 컬렉션](/ko/guides/content-collections/) 및 선택적 컬렉션 구성 파일을 저장하기 위해 예약되어 있습니다. 이 디렉터리에는 다른 파일이 허용되지 않습니다.

### `src/layouts`

[레이아웃](/ko/basics/layouts/)은 하나 이상의 [페이지](/ko/basics/astro-pages/)에서 공유되는 UI 구조를 정의하는 Astro 컴포넌트입니다.

`src/components` 디렉터리와 마찬가지로 이 디렉터리는 일반적인 규칙이지만 필수는 아닙니다.

### `src/pages`

[페이지](/ko/basics/astro-pages/)는 사이트의 새 페이지를 만드는 데 사용되는 특별한 종류의 컴포넌트입니다. 페이지는 Astro 컴포넌트일 수도 있고 사이트 콘텐츠의 일부 페이지를 나타내는 Markdown 파일일 수도 있습니다.

:::caution
`src/pages` 디렉터리는 Astro 프로젝트의 **필수** 하위 디렉터리입니다. 이 디렉터리가 존재하지 않으면 사이트의 페이지나 경로 또한 존재하지 않습니다!
:::

### `src/styles`

CSS 또는 Sass 파일을 `src/styles` 디렉터리에 저장하는 것은 일반적인 규칙이지만 필수는 아닙니다. 스타일이 `src/` 디렉터리 내 어딘가에 있으며, 올바르게 가져오기만 한다면, Astro는 스타일을 처리하고 최적화할 것입니다.

### `public/`

`public/` 디렉터리는 Astro의 빌드 프로세스 중 처리할 필요가 없는 프로젝트의 파일 및 자산을 위한 것입니다. 이 폴더의 파일은 그대로 빌드 폴더에 복사되어 사이트가 빌드됩니다.

이러한 동작으로 인해 `public/` 디렉터리는 이미지 및 글꼴과 같은 일반 자산이나 `robots.txt` 및 `manifest.webmanifest` 파일과 같은 특수 파일을 저장하는데 이상적입니다.

CSS 및 JavaScript 파일을 `public/` 디렉터리에 저장할 수 있지만 이 파일들은 최종 빌드에서 번들링되거나 최적화되지 않습니다.

:::tip
일반적으로 직접 작성한 CSS 및 JavaScript 파일은 `src/` 디렉터리에 저장합니다.
:::

### `package.json`

JavaScript 패키지 관리자가 종속성을 관리하는 데 사용하는 파일입니다. 또한 Astro를 실행하는 데 사용되는 스크립트(예: `npm start`, `npm run build`)를 정의합니다.

`dependencies`와 `devDependencies`는 `package.json` 파일에서 설정할 수 있는 [두 종류의 종속성](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file)입니다. 대부분의 경우 이는 동일하게 작동합니다. Astro는 빌드 시 모든 종속성을 필요로 하며 패키지 관리자는 두 종류의 종속성을 모두 설치합니다. 프로젝트를 시작하기 위해 모든 종속성을 `dependencies`에 두고, 특정 요구 사항이 있는 경우에만 `devDependencies`를 사용하는 것을 권장합니다.

프로젝트에 새 `package.json` 파일을 생성하는 데 도움이 필요하면 [수동 설치](/ko/install/manual/)를 확인하세요.

### `astro.config.mjs`

이 파일은 모든 시작 템플릿에서 생성되며 Astro 프로젝트에 대한 구성 옵션을 포함합니다. 이 파일에서 사용할 통합, 빌드 옵션, 서버 옵션 등을 설정할 수 있습니다.

구성 설정에 대한 자세한 내용은 [Astro 구성 가이드](/ko/guides/configuring-astro/)를 확인하세요.

### `tsconfig.json`

이 파일은 모든 시작 템플릿에서 생성되며 Astro 프로젝트에 대한 TypeScript 구성 옵션을 포함합니다. 일부 기능(예: npm 패키지 가져오기)은 `tsconfig.json` 파일이 없으면 편집기에서 완전히 지원되지 않습니다.

구성 설정에 대한 자세한 내용은 [TypeScript 가이드](/ko/guides/typescript/)를 확인하세요.
